<link rel="stylesheet" type='text/css' href="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/devicon.min.css" />

![](images/clock.png)

# Демонстрационное web-приложение сервиса Platform V DataSpace

## Приветсвие

Добро пожаловать в руководство по установке и настройке демонстрационного проекта Platform V DataSpace!<br>
В рамках данного материала будут подробно описаны все основные шаги, необходимые для развертывания учебного проекта в локальном окружении разработчика, установке всех необходимых зависимостей и инструментов. Также будет дана краткая характеристика применяемых подходов и технологий. Мы будем благодарны за любую конструктивную обратную связь, а также готовы ответить на все вопросы по внедрению и практической разработке с применением Platform V DataSpace.

## Понятие BaaS

**Backend as a Service** (backend как услуга) — модель, которая предоставляет полноценную среду разработки ПО в облаке провайдера. Она автоматизирует внутреннюю разработку, берет на себя работу с серверами и позволяет заказчику сосредоточиться на разработке интерфейса. Готовые инфраструктурные решения значительно упрощают работу разработчиков


## Общая информация о системе Platform V DataSpace

Platform V DataSpace является облачным решением для хранения и управления данными, реализующее концепции DааS (data-as-a-service) и BааS (backend-as-a-service), с продвинутым мониторингом и гибкими возможностями поиска и получения данных

![](images/platformv.png)

Platform V DataSpace входит в состав обширного набора продвинутых инструментов разработки и поддержки IT-инфраструктуры от Сбера

![](images/platformvtable.png)


## Ключевые преимущества Platform V DataSpace

- **Экономия** <br>Снижение расходов на создание backend-инфраструктуры

- **Мультиязычность** <br>Поддержка Java, JavaScript, Python, Go

- **Совместимость с GraphQL API** <br>Полноценная работа с популярным протоколом

- **Удобный интерфейс** <br>Визуальный редактор моделей, понятный всей команде  

- **Безопасность** <br>Основан на реальных внедрениях в enterprise-сегменте, позволяет реализовать импортозамещение


 
 ## Предметно-ориентированное проектирование <br>(domain-driven design, DDD)

DDD — это подход, который нацелен на изучение предметной области предприятия в целом или каких-то отдельных бизнес-процессов. Это отличный подход для проектов, в которых сложность (запутанность) бизнес-логики достаточно велика. Его применение призвано снизить эту сложность, насколько возможно.

Вне подхода DDD, когда программист пишет код, больше внимания он уделяет технологиям и инфраструктуре, например, как отправить сообщение, как его получить, закодировать, сохранить в базу данных, в какую именно базу данных.

Подход DDD говорит о том, что всё это, конечно, важно, но вторично. Бизнес главнее и должен стоять на первом месте. И чтобы вся эта штука заработала вместе, DDD учит нас (разработчиков) разговаривать с бизнесом на одном языке. Не на языке программирования, а на языке бизнеса. Это называется в DDD Единый язык (Ubiquitous language).

### Главные книги по DDD: красная, синяя и зелёная

DDD — довольно старый подход. Его использование выглядит разумным и вполне оправданным, но почему-то он всё ещё мало распространён, про него мало говорят на конференциях. Да что не так с этим DDD?

Есть предположение, что основная проблема в дефиците учебных материалов. Вся теория описана в нескольких книжках: красной, синей и зелёной. Говорят, что есть «ещё одна красная книжка», но её пока мало кто видел :)

Если вы решили начать изучать литературу по DDD, то лучше всего начать с «зелёной» книги. В ней Вон Вернон пробегается по верхушкам подхода и на простых примерах показывает его преимущества. Говорят, что перевод получился сомнительным, так что лучше читать в оригинале.

<table>

   <tr>
      <td>
         <a href="https://ozon.ru/t/WNo9pAw"><img height="250" src="images/red.png" /></a>
      </td>
      <td>
         <a href="https://ozon.ru/t/ZZaR4JB"><img height="250" src="images/blue.png" /> </a>
      </td>
      <td>
         <a href="https://ozon.ru/t/YAdLnYo"><img height="250" src="images/green.png" /> </a>
      </td>
   </tr>

</table>



## Необходимое программное обеспечение

+ <i class="devicon-git-plain colored"></i> Git 
https://git-scm.com/<br>
Система контроля версий

+ <i class="devicon-nodejs-plain colored"></i> Node.js v16.14.2
https://nodejs.org/en<br>
Применяется для сборки и запуска React-приложения

+ <i class="devicon-java-plain colored"></i> OpenJDK v18.0.2+9
https://jdk.java.net/archive/<br>
Необходимый компонент для запуска и работы Keycloak

+ <i class="devicon-vscode-plain colored"></i> Visual Studio Code
https://code.visualstudio.com/<br>
Любая IDE

+ Keycloak v17.0.1 https://github.com/keycloak/keycloak/releases/download/17.0.1/keycloak-legacy-17.0.1.zip<br>
Система идентификации и авторизации (Identity Identification Manager)

<br>

В данном учебном примере клиентское приложение развертывается в операционной системе Mac OS.<br>
Для Windows и Linux общий порядок шагов будет аналогичным, но с учетом с особенностей данных ОС.


## Описание проекта, ключевые файлы

Приложение создано с применением JS-библиотеки React, для сборки используется Webpack и Babel<br>
Кроме этого для использования GraphQL API применяется Apollo GraphQL

Apollo GraphQL – это js-фреймворк для работы с GraphQL API: связь с сервером, кеширование, обработка ошибок и т.п. 

![](images/front.jpeg)

**Ключевые файлы проекта**:

- model.xml - модель предметной области для DataSpace
- schema.graphql - GraphQL-схема API DataSpace
- .env - конфигурационный файл подключения frontend-приложения к серверу через язык запросов GraphQL
- FirstLoad.graphql - запрос для первоначальной загрузки данных о товарах
- permissions.json - JSON файл для загрузки в DataSpace информации об разрешенных для frontend запросов к серверу
- graphql/requests.graphql - GraphQL-запросы, осуществляющие основные функции приложения

- documentation - справочная информация о применяемых запросах и разрешениях
- src/components - React-компоненты приложения

## Пошаговый процесс развертывания

#### Подготовка файлов проекта

1. Создание директории для проекта<br>
``mkdir app``

2. Клонируем проект:<br> 
``cd app``<br>
``git clone https://gitverse.ru/sc/bvvmail/dataspace_demo_shop.git``
<br>в директории app будет создана вложенная директория ``online-shop``, в которой находится все необходимые для развертывания приложения файлы



#### Установка и настройка системы авторизации и идентификации Keycloak

3. Скачиваем систему авторизации и идентификации доступа KeyCloak <br>
https://github.com/keycloak/keycloak/releases/download/17.0.1/keycloak-legacy-17.0.1.zip

4. Распаковываем скачанный zip-архив Keycloak-legacy-17.0.1.zip и перемещаем директорию keycloak-17.0.1 в директорию проекта (app)

5. Открываем Терминал и переходим в директорию keycloak-17.0.1/bin

6. Запускаем KeyCloak командой ``./standalone.sh`` <br>
**Важно!** Перед запуском KeyCloak в системе должен быть установлен <a href="https://jdk.java.net/archive/">JDK</a>!<br>
KeyCloak выводит в консоль информацию о запуске

![](images/keycloak_cli.png)

7. Открываем Панель управления KeyCloak в браузере по адресу http://localhost:8080/auth/<br>
Указываем логин и пароль для создания администратора, для тестовых целей подойдет несложный, например admin 12345, нажимаем кнопку Create, далее логинимся в соответствии с созданным профилем

![](images/keycloak_admin.png)<br><br>
![](images/1.png)

Административная консоль Keycloak

![](images/2.png)


#### Создание пользователей и настройка прав доступа в системе Keycloak

8. Создаем новое рабочую область (realm) с названием orders

![](images/3.png)<br>v
![](images/4.png)


9. Создаем нового клиента для системы авторизации на сайте (под клиентом понимается именно компонент клиент - сервер, а не клиент интернет-магазина)<br>
Client ID: orders<br>
Root URL: http://localhost:3000

![](images/5.png)<br><br>
![](images/6.png)


10. Создаем роли для пользователей системы:
- customer (покупатель)
- manager (менеджер интернет-магазина)
- supervisor (старший менеджер интернет-магазина)
- vendor (поставщик, продавец)

![](images/7.png)<br><br>
![](images/8.png)<br><br>
![](images/9.png)

11. Создаем четырех пользователей системы, создаем для каждого пароли и устанавливаем их постоянными (система не будет предлагать сменить их после первого входа)

customer_user<br>
customer@mail.ru<br>
12345

manager_user<br>
manager@mail.ru<br>
12345

supervisor_user<br>
supervisor@mail.ru<br>
12345

vendor_user<br>
vendor@mail.ru<br>
12345

![](images/10.png)<br><br>
![](images/11.png)<br><br>
![](images/12.png)



12. Для пользователя vendor_user также создаем аттрибут vendor_id со значением "SberDevices". Это необходимо для демонстрации возможности системы по обеспечению прав доступа и передачи разным пользователям только той информации, к которой у них есть доступ

![](images/13.png)

13. Добавляем пользователям соответствующее роли

![](images/14.png)


14. Добавляем передачу параметра vendor_id в составе JWS-токена (необходимо для обеспечения корректного разграничения прав доступа)

**Clients orders Mappers Create Protocol Mappers**

![](images/15.png)

Clients - orders - Mappers - Create - vendor_id (тип User Attribute, User Attribute и Token Claim Name - vendor_id, Claim JSON Type - String)


15. Создание модели предметной области в визуальном редакторе Platform V DataSpace.<br>
Открываем Smart Market studio (Авторизация по Sber ID или почте) https://developers.sber.ru/dev<br>
Создаем новый проект Platform V DataSpace, имя Shop

![](images/16.png)<br><br>
![](images/17.png)<br><br>

После создание проекта попадаем в визуальный конструктор моделей предметной области DataSpace

![](images/18.png)


16. Импортируем в проект готовую модель предметной области (файл model.xml проекта)

![](images/19.png)<br><br>
![](images/20.png)

Данный редактор предоставляет широкие возможности манипулирования и определения ключевых сущностей предметной области, использую все основные подходы предметно-ориентированного проектирования

17. После загрузки в редактор модель должна быть выпущена, т.е. на стороне сервера созданы и запущенны все необходимые компоненты и сервисы, обеспечивающие функционирование модели и обмен данными. По завершении выпуска модели необходимо указать ее версию для редактирования - 0.0.2 (исходная версия модели - 0.0.1)

![](images/21.png)<br><br>
![](images/22.png)<br><br>
![](images/23.png)<br><br>
![](images/24.png)



#### 

18. Настройка локального приложения для работы с DataSpace посредством GraphQL

GraphQL — это язык запросов и серверная среда для API с открытым исходным кодом. Он появился в Facebook в 2012 году и был разработан для упрощения управления конечными точками для API на основе REST

Копируем значение Ссылка на endPoint jwt graphql и вставляем его в файл .env проекта в качестве значения параметра DS_ENDPOINT (например DS_ENDPOINT=https://smapi.pv-api.sbc.space/jwt/ds-7376253516743639041/graphql)

![](images/25.png)<br><br>
![](images/26.png)


19. Для корректной совместной работы системы авторизации KeyCloak и DataSpace необходимо настроить ключи JSON Web Key Sets. Для этого создаем в корне приложения файл ``certs.json``

20. Получаем открытую часть ключа KeyCloak, перейдя по ссылке http://localhost:8080/auth/realms/orders/protocol/openid-connect/certs

![](images/27.png)

21. Копируем полученный ключ в файл certs.json, для удобства чтения JSON можно отформатировать средствами VS Code или сторонних расширений

![](images/28.png)



22. Загружаем полученный ключ в DataSpace в разделе Разрешения -> Загрузить JSON Web Key Sets

![](images/29.png)

23. Загружаем разрешения на запросы от frontend-части приложения к DataSpace из файла permissions.json из файлов проекта

![](images/30.png)<br><br>
![](images/31.png)<br><br>
![](images/32.png)


24. Поскольку в нашем интернет-магазине еще нет никаких данных нам необходимо загрузить их в DataSpace, выполнив GraphQL запросы из файла FirstLoad.graphql в конструкторе GraphQL запросов. Копируем запросы из файла, вставляем в левой части конструктора и нажимаем кнопку в центре, данные загружаются в DataSpace. Теперь в нашем интернет-магазине появились товары!

![](images/33.png)


25. Сборка и запуск React-приложения.<br>
Последовательно выполняем в терминале следующие команды:<br><br>
 Установка необходимых модулей Node.js с помощью менеджера пакетов npm<br>
 ``npm install``<br><br>
 Сборка React-приложения<br>
 ``npm run codegen``<br><br>
 Запуск приложения<br>
 ``npm start`` <br><br>

 


26. Открываем приложение в браузере:<br>
[http://localhost:3000/](http://localhost:3000/)

27. Авторизуемся например под пользователем customer_user (12345)<br>
Мы попадаем на главную страницу интернет магазина, где можем просматривать товары, помещать их в корзину (кнопки справа)<br>



![](images/34.png)<br><br>
![](images/35.png)<br><br>
![](images/36.png)<br><br>

Важно, что разделы сайта **All orders** и **Orders details for vendor** в соответствии с заданной схемой разрешений пользователю **customer_user** недоступны

![](images/37.png)<br><br>
![](images/38.png)

При этом если мы авторизуемся на сайт под пользователем vendor_user, для которого был создан аттрибут vendor_id = SberDevices мы сможем просмотреть информацию раздела Orders details for vendor, доступа будет разрешен

![](images/39.png)

Более детально механизм работы JWT-токенов можно увидеть, открыв инструмент мониторинга сети браузера и выбрать какой-то GraphQL-запрос

![](images/40.png)<br><br>

Скопировав значение ключа и зайдя на сайт <a href="https://jwt.io/">https://jwt.io/</a>  можно его декодировать, среди параметров мы увидим vendor_id, передача именно этого параметра в составе JWT-токена и позволяет Keycloak распознать пользователя и предоставить ему доступ к разрешенным разделам сайта

![](images/41.png)

Поздравляем! Вы справились!<br>
Добро пожаловать в демонстрационное приложение Platform V DataSpace!

Корректно завершить работу web-приложения, а также KeyCloak возможно комбинацией - Ctrl + С в терминале с запушенными сервисами


## Средства мониторинга

Platform V DataSpace обладает развитыми средствами анализа производительности и мониторинга. Можно анализировать скорость работы запросов GraphQL, загруженность CPU, сети, дискового пространства и много е другое.<br>
Доступ к средствам мониторинга можно получить в Smart Market Studio, вкладка Детали:

![](images/monitoring1.png)
![](images/monitoring2.png)


## Полезные ссылки

Портал Сбера для разработчиков<br>
https://developers.sber.ru/dev

Platform V<br>
https://platformv.sbertech.ru/

Platform V DataSpace<br>
https://platformv.sbertech.ru/products/instrumenty-razrabotchika/dataspace

Документация Platform V DataSpace<br>
https://client.sbertech.ru/docs/public/APT/1.12.0/DSPC/1.12.0/


------------
### JWT & JWKS

Open ID Connect<br>
https://openid.net/developers/how-connect-works/

JWKS<br>
https://auth0.com/docs/secure/tokens/json-web-tokens

JSON Web Tokens<br>
https://jwt.io/

------------
### Язык запросов GraphQL

Официальный сайт GraphQL<br>
https://graphql.org/

Кодогенерация с помощью GraphQL<br>
https://the-guild.dev/graphql/codegen#!

GraphQL в DataSpace<br>
https://client.sbertech.ru/docs/public/APT/1.12.0/DSPC/1.12.0/documents/dataspace-core-graphql-protocol/index.html

Работа со строковыми выражениями в DataSpace<br>
https://client.sbertech.ru/docs/public/APT/1.12.0/DSPC/1.12.0/documents/string-expressions/index.html

------------
### Инструменты для разработчиков от Сбера

GIGACHAT - диалоговая AI-модель, которая отвечает на вопросы, сочиняет тексты, пишет код и рисует картинки. Говорит на русском и понимает английский.<br>
https://developers.sber.ru/gigachat/

GIGACODE - это AI-ассистент разработчика, который позволяет ускорить процесс написания кода, предлагая наиболее вероятные и релевантные подсказки<br>
https://gigacode.ru/

GITVERSE - российская платформа для работы с исходным кодом<br>
https://gitverse.ru/


------------
## Завершение

В результате последовательного и внимательного выполнения всех шагов данного руководства вы получите полноценное fullstack web приложение, демонстрирующее базовые возможности сервиса Platform V DataSpace. Команда Сбера активно ведет разработку новых функций и возможностей, постоянно выходят обновления, новые версии платформы, инструментов для разработчиков.
<br><br>Всю актуальную информацию, новости, а также ответы на вопросы вы можете оперативно получать через наши каналы в социальных сетях, вступайте и подписывайтесь:

TG канал Sber Developer News<br>
https://t.me/SberDeveloperNews

TG группа пользователей developers.sber.ru и продуктов SberDevices<br>
https://t.me/smartmarket_community

Habr<br>
https://habr.com/ru/companies/sberbank/profile/

## Спасибо! 
<br><br>

![](images/sb.png)<br><br>